Repository navigation
trains: exact forward-mode derivatives of designed refocusing trains - #57
Merged
Merged
Conversation
The C++ train kernels carry one extra set of EPG states per direction through the echo-by-echo recursion, so prescribed_flips, effective_te and busse_flips return exact derivatives (signal_tangents, flip_tangents, jacobian=True). The Busse shooting takes its Newton and MINPACK Jacobians from them instead of differencing the residual. Forward mode also silences the torch.jit.script deprecation whatever warning class PyTorch raises it as. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01MFB6QKxkFL4hC7MC4RCb2V
…ent kernels Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01MFB6QKxkFL4hC7MC4RCb2V
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Requested by Matteo · project thread
What changed
The
_trains_cpukernels can now return exact derivatives as well as values. They carry one extra set of EPG states per direction through the echo-by-echo recursion, which is forward mode. Each pulse's angle is solved in closed form, so its derivative follows from the implicit function theorem when the echo is met, fromatan2(c, b)at an extremum, and is zero at an end of [0, π]. The new public options:prescribed_flips(..., signal_tangents=, first_flip_tangents=)also returns the derivatives of the angles and of the echoes.effective_te(..., flip_tangents=)also returns the derivatives of the echo times.busse_flips(..., jacobian=True)also returns(…, echoes, 3), the derivatives of the train with respect tomin_flip,centre_flipandmax_flip. They come from the implicit function theorem over the shooting, withmax_flipentering both directly and through the opening transient.The Busse shooting's damped Newton steps and its MINPACK fallback now take their Jacobian from these derivatives instead of differencing the residual (
_STEP_DEGis gone)._pssand_targetcarry their own derivatives.Forward mode's
torch.jit.scriptdeprecation is silenced whatever warning class PyTorch raises it as. PyTorch 2.15 raises aFutureWarning.Why
Finite differences in the train design were numerically fragile. This PR provides the derivatives the pypulseqpp Busse/PD optimizers need so they can drop finite differences entirely (companion pypulseqpp PR to follow). The design runs on the scanner host's CPU.
Validation
pytest tests/trains: 119 passed. New tests check every set of derivatives against central differences:pytest tests -n 4: 1673 passed, 327 skipped, 1 failed. The failure wastest_an_image_quality_design_fits_in_its_budgetat 3.01 s against its 3.0 s wall-clock budget under parallel load. It passes alone (3.00–3.10 s here) and does not touch the trains.pre-commit run --all-files: clean.Documentation impact
docs/api/trains.mdgains a paragraph on the derivatives.bash scripts/build_docs.shwas not run in this session.Checklist
pytest tests/passes locally (except the wall-clock budget test above), and new tests cover what changed.pre-commit run --all-filesis clean.bash scripts/build_docs.shnot run here.Generated by Claude Code